Backup and restore (virtual appliance)

This page will describe how to backup and restore a DCT appliance engine at a high level, in cases where you might need to:

  • Recover from a failure of underlying hardware.

  • Recover from loss or corruption of configurations due to user error.

  • Migrate the DCT appliance to a different VM, hypervisor, data center, etc.

  • Create a copy of the DCT appliance to test a new version or configuration without affecting the primary instance.

Many hypervisor-based technologies, such as VM snapshots, exist and can be used to backup and restore DCT appliances. Those technologies are not covered by this documentation.

The DCT appliance has a built-in backup and restore solution which can be used to take point-in-time backups of the DCT application metadata. This includes all data in the DCT application, such as the list of accounts along with their passwords, access groups, registered engines, hyperscale orchestrators, metadata on connected dSources, VDBs, bookmarks, compliance jobs, compliance connectors, etc.

However, the DCT appliance setup information such as network, storage, time, registration, system users, and TLS certificates are not included in the backup.

DCT backups can only be used to restore the DCT application itself and do not protect against failure or loss of data of the connected engines or hyperscale orchestrators.

DCT appliance backup and restore information

Backup

The DCT backup may include sensitive data such as passwords to connect to engines, API keys to connect to hyperscale orchestrators, and personally identifiable information. While the data is encrypted in transit, make sure that you store the backup in an appropriate location. Make sure that the backup location adheres to your company policy on access control and encryption at rest. It is a best practice to perform the backup operation from a dedicated server, and not from an operator machine. For this reason, the DCT appliance does not provide a web user interface for the backup but mandates the use of API calls scripting.

A backup operation can be taken while the DCT application is in use but has a light impact on the performance of the application, so expect increased latency to API and UI experience during the operation.

The duration of the operation depends on the size of metadata to be included in the backup and the performance of the system, but usually ranges from 1 to 10 minutes. The size of the produced backup file also depends on the size of the metadata, typically ranging from 1GB to 10GB.

Restore

Restoring from a backup is a destructive operation. All DCT application data on the appliance onto which the restore operation is performed will be permanently deleted.

The DCT appliance onto which the restore operation is performed must have been setup via the setup wizard. As indicated above, the setup configuration information (system user, network, time, storage, TLS certificates, registration) is not part of the DCT backup and will not be restored.

It can be the same or a different DCT appliance than the appliance from which the backup was taken. If you are restoring a backup to a different DCT appliance, and the original DCT appliance is still running, at the end of the restore operation both DCT appliances will be pulling data (and controlling) the registered engines and hyperscale orchestrators.

The DCT appliance onto which the restore operation is performed can have a different system confirmation as long as the following requirements as satisfied:

  • The metadata disk size must be greater than the size of the metadata in the backup. Only the effectively used data matters.

  • Network setup (network interfaces, DNS resolvers) must allow DCT to connect to registered engines and hyperscale orchestrators, or DCT would not work properly post restore.

  • The DCT appliance must be greater or equal to the backup version (i.e. the version of the DCT appliance when the backup was taken). If the version of the DCT appliance is greater than the backup version, the restore process will automatically upgrade the backup data to the DCT appliance version. In other words, at the end of the restore operation the DCT appliance version will always be the same DCT appliance version before the restore operation, regardless of the backup version.

Backup and restore process

Backup

This section describes the various API calls used to take a DCT appliance backup. The examples use the curl API client, but any HTTP client can be used.

1. Establish a new API session. To establish an API session and store the session information in a cookie (this example uses ~/cookies.txt):

Copy 
curl -X POST https://<dct-appliance-hostname>/resources/json/delphix/session -c ~/cookies.txt -H "Content-Type: application/json" -d \
'{"type": "APISession", "version": {"type": "APIVersion","major": 1,"minor": 4, "micro": 3}}'

Expected output:

Copy 
{"type":"OKResult","status":"OK","result":{"type":"APISession","version":
{"type":"APIVersion","major":1,"minor":4,"micro":3},"locale":null,"client":null},"job":null,"action":null}

2. Login. To login, make a new API call using the same cookies file as the one to establish the session. Substitute the dct-appliance-hostname, and the username and password of a system user.

Copy 
curl -X POST https://<dct-appliance-hostname>/resources/json/delphix/login \
-b ~/cookies.txt \
-c ~/cookies.txt \
-H "Content-Type: application/json" \
-d '{"type": "LoginRequest","username": "<sysadmin-user-name>","password": "<sysadmin-password>","target": "SYSTEM"}'

Expected output:

Copy 
{"type":"OKResult","status":"OK","result":"USER-1","job":null,"action":null}

3. Download the backup. Make an API call to the downloadAppBackup API endpoint and direct the response to a file on disk, at the desired location.

Copy 
curl https://<dct-appliance-hostname>/resources/json/delphix/system/downloadAppBackup \
--fail \
-b ~/cookies.txt \
-o /path/to/backup.zip

4. Verify the API call has completed successfully. Since the output is redirected to a file, the above example is using the --fail option of curl, which causes the command to exit with a non-zero exit code if the HTTP response code indicates a failure.

Copy 
[[ $? -eq 0 ]] && echo "backup success" || echo "backup failed"
backup success

Since version 7.76.0, curl has a --fail-with-body option which can be used instead of --fail and will print error messages directly to the console.

Restore

Follow the instructions provided in the Backup step-by-step guide section to establish a session and login, then call the uploadRestoreAppBackup API endpoint:

Copy 
curl https://<dct-appliance-hostname>/resources/json/delphix/system/uploadRestoreAppBackup \
-b ~/cookies.txt \
-F data=@/path/to/backup.zip

Expected output:

Copy 
{"type":"OKResult","status":"OK","result":"","job":null,"action":"ACTION-24"}

Troubleshooting

If the backup or restore processes fails with a 403 response code, for instance with the following error message:

The requested URL returned error: 403

Either the DCT appliance does not support backup/restore (introduced in DCT version 2025.2.0.0) or the appliance has not been fully setup. Make sure the DCT version is 2025.2.0.0 or newer and if necessary, use the initial setup wizard to configure the DCT appliance.

If you are seeing an error such as:

curl: (60) SSL certificate problem: self signed certificate in certificate chain

Then curl is unable to validate the SSL certificate chain configured on your DCT appliance. By default, the DCT appliance uses an insecure self-signed certificate, which would rightfully cause curl to display the above error. If you are unable to replace the self-signed certificate, and you understand the risk, you may use the -k flag to disable certificate verification (this applies both to the provided script and the curl command).

Use cases

Scenario one: Backup and restore onto the same DCT appliance after a manual error

This use case covers a scenario where a DCT administrator created a regular task, for instance a cronjob, to take a backup of the DCT nightly and retain the most recent 10 entries. The storage requirement will be 10 times the size of the DCT backup, which is often between 1GB and 10GB. The backup process runs when DCT is running, but is scheduled at night to minimize the impact on UI and API latency of users activity.

The administrator later notices a script they use has a defect, which has now deleted the access group configuration in their DCT instance. Since reconstructing them manually is time consuming, and they have a recent backup, they choose to restore from the most recent backup.

With the DCT appliance is still running, they run the restore script and observe that DCT, including the access group configurations, are back to the exact state they were in when the backup was taken.

They notify all DCT users that any action taken on DCT since the last backup time might have been lost. In particular, DCT bookmarks created since the last backup are no longer present in DCT.

Scenario two: Backup and restore onto the same DCT appliance after a hardware failure

Consider this scenario to have the same backup process as the previous scenario, nightly backups of the DCT appliance. This time the DCT administrator is notified by the hypervisor administrator that the storage array used to store the DCT appliance virtual machine had a failure, and the virtual machine is in a failed state.

The hypervisor administrator offers to provision a new virtual machine with the same configuration as the original virtual machine (same hostname, IP address, etc.). The DCT administrator uses the initial setup wizard to configure the DCT appliance setup, selecting the appropriate settings for network interfaces, storage, TLS configuration. The DCT administrator disregards the bootstrap API key generated during initial setup, as they will immediately restore from the DCT backup.

As soon as initial setup has completed, the DCT administrator runs the restore script against the latest available backup, and DCT is restored to the state of that backup.

They notify all DCT users that any action taken on DCT since the last backup time might have been lost. In particular, DCT bookmarks created since the last backup are no longer present in DCT.

Scenario three: Testing a new DCT version

This scenario has the DCT administrator evaluating a new version of the DCT appliance to self-educate on new features, without disrupting current users. They provision a new virtual machine for that purpose, and install a more recent DCT appliance version.

The DCT administrator uses the initial setup wizard to configure the new DCT appliance. Then they take a backup of the original DCT appliance and immediately restore it onto the new DCT appliance.

At the end of the restore operation, both DCT appliances are pulling data from, and controlling all registered engines. The DCT administrator learns the new features and differences in the DCT appliance version, and tears down the new DCT appliance when the testing is complete.